home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / editors / bcut / bcut.doc next >
Text File  |  1993-08-31  |  13KB  |  396 lines
  1.  
  2.             PCX Brush Cutter
  3.               Version 1.0
  4.                Vu Nguyen
  5.  
  6.  
  7.  
  8. INTRODUCTION:
  9.  
  10. This is a brush cutting program for programmers that need a program that reads
  11. PCX image file and clipps brushes and saves them to a simple raw format.
  12. I don't know about anybody else but when i was searching for something like
  13. this on the net, nothing like it existed; so, i decided to write one and
  14. release it to the public domain hoping it will help some other unfortunate
  15. soul. I also included a command line conversion program (called pcx2raw.exe
  16. and pcxpal.exe) to convert a given PCX image file to my own raw format and
  17. to extract the palette in a PCX file. 
  18.  
  19.  
  20.  
  21. SOFTWARE AGREEMENT:
  22.  
  23. This is freeway so give it to whoever/whomever wants it. There should be no
  24. charge for this software except in the case of distribution. In such cases the
  25. cost should only be for media only.  If you think i did a good job and
  26. deserve to be rewarded, then send the money to your favorite charity or to
  27. the 386 bsd development group. Of course this excludes regarding yourself as
  28. your own favority charity organization. Have fun and enjoy.
  29.  
  30.  
  31. CONTENTS:
  32.  
  33. When you unzip the bcut.zip file you should get the following...
  34.  
  35. BCUT     EXE    102222 08-29-93   7:49p
  36. STD      FNT      3950 12-07-92   3:55p
  37. PCX2RAW  EXE     33266 07-25-93  10:50p
  38. PCXPAL   EXE     33042 07-26-93   7:34p
  39. BCUT     DOC     12824 08-31-93   1:38p
  40.         8 file(s)     185061 bytes
  41.  
  42.  
  43.  
  44. SYSTEM REQUIREMENTS:
  45.  
  46. The only requirements for this program is that you use a 386 or better, a VGA
  47. display adapter, have plenty of memory, and a mouse. bcut was written in
  48. protected mode so anything less than a 386 won't work. as for the memory
  49. requirements, the more memory you have the better it works. Rather, the more
  50. brush you can cut and the more PCX pictures you can display. About the mouse,
  51. i have to say sorry to the people that don't have one. it's just simply too
  52. difficult to do something like brush cutting without a mouse. I guess now is
  53. a good time to consider buying a one.  One other thing, the PCX files are
  54. assumed to be 256 color PCX files. Anything else won't work.
  55.  
  56.  
  57.  
  58. STD.FNT FILE:
  59.  
  60. This is the font file used by bcut. without this you won't be able to read
  61. anything you type because nothing will come up on the screen. Make sure this
  62. file resides at the root of your C drive.
  63.  
  64.  
  65.  
  66. COMMAND LINE:
  67.  
  68. You can load multiple file in bcut when you use the program by typing...
  69.  
  70.     bcut file1.pcx file2.pcx file3.pcx
  71.  
  72. This will load all three file into the three different buffers. and you can
  73. change around by using the F1 and F2 keys. Look at the next section for more
  74. details.
  75.  
  76.  
  77.  
  78. KEYBOARD AND MOUSE USAGE:
  79.  
  80. At one point i was going to put a menu system in for this program but decided
  81. against it because it takes too long to select a menu item. Instead i decided
  82. to use the keyboard and mouse together. The key strokes are shown below.
  83.  
  84.     IN CUTTING MODE:
  85.  
  86.         a/A - Add current brush to a brush list. The brush's
  87.               offset can later be modified in the offset
  88.               modification part of bcut.
  89.  
  90.         b/B - Start the cutting process. After pressing this
  91.               button you should see a cross hair. The by pressing
  92.               the LMB (Left Mouse Button) the cross hair will
  93.               change to a selection box. Now move the mouse to the
  94.               desired area and press the LMB again. The region will
  95.               then be clipped out and appear as the mouse cursor.
  96.               If you have made a mistake and wish to cancel the
  97.               current region, just press the RMB (Right Mouse Button)
  98.               and the operation will be aborted.
  99.  
  100.         h/H - The online help menu
  101.  
  102.         l/L - Load new PCX file. Sorry, you have to type in the
  103.               file name. maybe i'll put in a mouse selection deal
  104.               in the future.
  105.  
  106.         m/M - Modify the offset of the brushes in the brush list.
  107.               Note that each buffer contains different brush lists.
  108.  
  109.         p/P - Pick a brush from the brush list. This is useful
  110.               if you decide to save only one brush instead of a
  111.               list of brushes. When picking a brush you can use
  112.               the n/N key for the next brush and the p/P key for
  113.               the previous brush. To accept the brush you can press
  114.               either RETURN/SPACE.
  115.  
  116.         q/Q - quit
  117.  
  118.         r   - Load an individual brush. I normally call the single
  119.               brush file [filename].raw to distinguish from the
  120.               brush list files, which i call [filename].pck. you,
  121.               however, can decide to call what ever you like but
  122.               becareful not to load a single brush file as a packed
  123.               brush file. The results will be unpredictable.
  124.  
  125.         R   - Load a packed brush file for the current PCX image
  126.               buffer. If there were brushed when this operation is
  127.               executed, the other brushes will be erase.
  128.  
  129.         s/S - Save current brush as a single brush file. You must
  130.               either pick a brush from the brush list or clipped
  131.               a region before executing this key stroke.
  132.  
  133.         z/Z - This will clear out the current brush list.
  134.  
  135.         PgUp/PgDn - This will lighten or darken the color of
  136.                 the background so that brushes can be seen
  137.                 easily.
  138.  
  139.         Home - This will reset the image so that the image's
  140.                upper left hand corner will correspond with the
  141.                screen's upper left hand corner.
  142.  
  143.         Arrow UP/DOWN/LEFT/RIGHT - This will scroll the image
  144.                        around if you image is bigger
  145.                        than 320x200.
  146.  
  147.         F1  - Will go to the next buffer. Currently there are only
  148.               3 buffers and you can switch around by using this key
  149.               and the F2 key.
  150.  
  151.         F2  - Previous buffer.
  152.  
  153.         .   - This will clear the current brush. Pressing the RMB
  154.               will perform the same action.
  155.  
  156.  
  157.  
  158.     IN MODIFYING BRUSH OFFSET MODE:
  159.  
  160.         Arrow UP/DOWN/LEFT/RIGHT - This will change the current
  161.                        brush's offset. You should be
  162.                        able to see the brush change
  163.                        position relative to the brush's
  164.                        origin.
  165.  
  166.         c/C - Clears the current brush list and returns to the
  167.               brush cutting mode.
  168.  
  169.         d/D - Delete current brush from brush list. If the current
  170.               brush is the last brush in the list, bcut will
  171.               automatically switch back to brush cutting mode.
  172.  
  173.         f/F - Save the current brush list as a raw bitmap font
  174.               format. There has to be a total of 94 brushes with
  175.               the same width and height in order for this operation
  176.               to work. This command assumes that the first brush
  177.               represents the '!' character and the last brush is
  178.               the '~' character. refer to an ascii table and you
  179.               will see the range of characters. This is my own
  180.               hoaky font format for when i need graphical fonts in
  181.               my program. The file format is shown in the FILE FORMAT
  182.               section.
  183.  
  184.         h/H - The online help menu.
  185.  
  186.         l/L - Load a packed brush file. This operation will erase
  187.               all existing brush in the brush list.
  188.  
  189.         m/M - This operation will append a packed brush list to
  190.               the current brush list.
  191.  
  192.         n/N - Next brush.
  193.  
  194.         p/P - Previous brush.
  195.  
  196.         q/Q/ESC - Quit and return to brush cutting mode.
  197.  
  198.         s/S - save the current brush list as a packed brush format.
  199.  
  200.         LMB - This will alter the brush's offset just like the
  201.               arrow keys except much faster.
  202.  
  203.         RMB - This will move the brush's origin to a different
  204.               location.
  205.  
  206.         Home - This will reset the origin to the center of the screen.
  207.  
  208.  
  209.  
  210. FILE FORMAT:
  211.  
  212. The file format are as follows:
  213.  
  214.     Raw format - This is the most basic format of them all, even though
  215.              all the format are actually very simple. The first four
  216.              longwords are used for the width, height, xoffset, and
  217.              yoffset respectively. The remaining data is the actual
  218.              image. Simple. A diagram is shown below.
  219.  
  220.         +-------+--------+----------+----------+-----------+
  221.         | Width | Height | x offset | y offset | image ... |
  222.         +-------+--------+----------+----------+-----------+
  223.          4 bytes 4 bytes   4 bytes    4 bytes    n bytes
  224.  
  225.  
  226.     Packed Format - This format is nothing other than an encapsulated
  227.             raw format. Essentially, the first longword contains
  228.             to total number of raw brushes and the remainder of
  229.             the file contains the raw brushes.
  230.  
  231.         +-------+-------------------------------------------+
  232.         |       |+-----------+-----------+-----------+-----+|
  233.         | total || raw brush | raw brush | raw brush | ... ||
  234.         |       |+-----------+-----------+-----------+-----+|
  235.         +-------+-------------------------------------------+
  236.          4 bytes
  237.  
  238.  
  239.     Font Format - The font format assumes that all 94 bitmap characters
  240.               have the same width and height. The maximum width
  241.               and height of any given character is 255 (still mighty
  242.               big if you ask me). The first 2 unsigned characters
  243.               represents the width and the height of the font
  244.               respectively, and the remainder of the file is the actual
  245.               bitmaps themselves. The figure below shows the layout.
  246.  
  247.         +-------+--------+---------------+
  248.         | width | height | 94 images ... |
  249.         +-------+--------+---------------+
  250.          1 byte   1 byte
  251.  
  252.  
  253.  
  254. SAMPLE CODE:
  255.  
  256. #include <stdio.h>
  257. #include <stdlib.h>
  258.  
  259. struct {
  260.   unsigned long w;
  261.   unsigned long h;
  262.   long x_offset;
  263.   long y_offset;
  264.   unsigned char *image;
  265. } raw;
  266.  
  267. struct {
  268.   unsigned char w;
  269.   unsigned char h;
  270.   unsigned char alphabet;
  271. } font;
  272.  
  273. struct raw *LoadRaw(char *filename)
  274. {
  275.   FILE *fd;
  276.   struct raw *r;
  277.  
  278.   if ((fd = fopen(filename,"rb")) == 0) return 0;
  279.   if ((r = calloc(1,sizeof(raw)) == 0) {
  280.     fclose(fd);
  281.     return 0;
  282.   }
  283.   fread(&r->w,sizeof(long),1,fd);
  284.   fread(&r->h,sizeof(long),1,fd);
  285.   fread(&r->x_offset,sizeof(long),1,fd);
  286.   fread(&r->y_offset,sizeof(long),1,fd);
  287.   if ((r->image = (unsigned char *)malloc(r->w * r->h)) == 0) {
  288.     free(r);
  289.     fclose(fd);
  290.     return 0;
  291.   }
  292.   fread(r->image,sizeof(char),r->w*r->h,fd);
  293.   fclose(fd);
  294.   return r;
  295. }
  296.  
  297. struct raw *LoadPCK(char *filename, unsigned long *t)
  298. {
  299.   FILE *fd;
  300.   unsigned long i;
  301.   struct raw *list;
  302.  
  303.   if ((fd = fopen(filename,"rb")) == 0) return 0;
  304.   fread(t,sizeof(long),1,fd);
  305.   if ((list = (struct raw *)calloc(*t,sizeof(struct raw))) == 0) {
  306.     fclose(fd);
  307.     return 0;
  308.   }
  309.   for(i=0;i<*t;i++) {
  310.     fread(&list[i].w,sizeof(long),1,fd);
  311.     fread(&list[i].h,sizeof(long),1,fd);
  312.     fread(&list[i].x_offset,sizeof(long),1,fd);
  313.     fread(&list[i].y_offset,sizeof(long),1,fd);
  314.     if ((list[i].image = (unsigned char *)
  315.             malloc(list[i].w * list[i].h) == 0) {
  316.         for(i=0;i<*t;i++) if (list[i].image) free(list[i].image);
  317.         free(list);
  318.         fclose(fd);
  319.         return 0;
  320.     }
  321.     fread(list[i].image,sizeof(char),list[i].w*list[i].h,fd);
  322.   }
  323.   fclose(fd);
  324.   return list;
  325. }
  326.  
  327. struct font *LoadFont(char *filename)
  328. {
  329.   FILE *fd;
  330.   font *f;
  331.  
  332.   if ((fd = fopen(filename,"rb")) == 0) return 0;
  333.   if ((f = (struct font *)calloc(1,sizeof(struct font)) == 0) {
  334.     fclose(fd);
  335.     return 0;
  336.   }
  337.   fread(&f->w,sizeof(char),1,fd);
  338.   fread(&f->h,sizeof(char),1,fd);
  339.   if ((f->alphabet = (unsigned char *)malloc(f->w * f->h * 94)) == 0) {
  340.     free(f);
  341.     fclose(fd);
  342.     return 0;
  343.   }
  344.   fread(f->alphabet,sizeof(char),f->w*f->h*94,fd);
  345.   return f;
  346. }
  347.  
  348. The best way to access the individual characters in the alphabet is by
  349. doing the method below.
  350.  
  351.     character = (char_val - '!') * fontwidth * fontheight
  352.  
  353. in other words...
  354.  
  355.  
  356. unsigned char *Character(struct font *f, char c)
  357. {
  358.   if ((c < '!') || (c > '~')) return 0;
  359.   return f->alphabet * ((c - '!') * f->w * f->h);
  360. }
  361.  
  362.  
  363.  
  364. COMMAND LINE UTILS:
  365.  
  366. pcx2raw.exe - This program will also convert an entire PCX image into a giant
  367.           raw brush. Note that during the conversion process the image
  368.           looses the palette. To recover the palette use pcxpal.exe.
  369.           To use pcx2raw just give a source file and destination file
  370.           name. e.g.
  371.  
  372.             pcx2raw hello.pcx world.raw
  373.  
  374. pcxpal.exe  - This program extract the palette from a given pcx file. The
  375.           palette file is stored as an RGB set. In other words, the
  376.           first three unsigned bytes represents the first RGB set,
  377.           the next three unsigned bytes is the next RGB set and so on.
  378.           To use pcxpal just give a source file and a destination file
  379.           name.
  380.  
  381.             pcxpal hello.pcx world.pal
  382.  
  383.  
  384.  
  385. CONCLUSION:
  386.  
  387. And there you have it, ways of using bcut to put graphics and/or animation
  388. into your own program. well, actually you have to do the display part yourself;
  389. i just provided and easier way of accessing the images. I hope you have many
  390. uses for this program and that it does help you in doing something or other.
  391. If you have any comments or suggestions or would like the source code, just
  392. e-mail me at vun@satyrs.csufresno.edu or at vun@kron.cs.csufresno.edu. Good
  393. luck to you.
  394.  
  395.  
  396.